# AI API reference

The [AI API](/product/apis-integrations/ai-api) provides the following endpoints.

## `/query/completions`

Generate a Cube query that can be used to answer a user's question, and (optionally) run the query and return its results.

| Parameter  | Required | Description                                                                                     |
| ---------- | -------- | ----------------------------------------------------------------------------------------------- |
| `messages` | ✅ Yes   | An array of messages in the format: `{ "role": "user" \| "assistant", "content": "string" }`    |
| `views`    |          | An array of view names (used to limit the views that the AI API can use to generate its answer) |
| `runQuery` |          | Boolean (true or false) whether to run the query and return its results                         |

Response

- `message` - A message from the AI assistant describing the query, how it was chosen, why it could not generate the requested query, etc.
- `cube_query` - A Cube [Query](/product/apis-integrations/rest-api/query-format) that could be used to answer the given question

### Examples

#### Without `runQuery`

Example request:

```bash{outputLines: 1,3-9,11-15}
curl \
 -X POST  \
 -H "Content-Type: application/json" \
 -H "Authorization: EXAMPLE-API-TOKEN" \
 --data '{ "messages": [{ "role": "user", "content": "What cities have the highest aov this year?" }]}' \
 https://YOUR_CUBE_API/cubejs-api/v1/ai/query/completions
```

Example response:

```json
{
  "message": "To find the cities with the highest Average Order Value (AOV) this year, we can use the Orders View. This query will aggregate data to calculate the average order value per city for the current year.",
  "cube_query": {
    "measures": ["orders_view.average_order_value"],
    "dimensions": ["orders_view.users_city"],
    "timeDimensions": [
      {
        "dimension": "orders_view.created_at",
        "granularity": "year",
        "dateRange": "this year"
      }
    ],
    "order": {
      "orders_view.average_order_value": "desc"
    },
    "limit": 10
  }
}
```

#### With `runQuery`

```bash{outputLines: 1,3-9,11-15}
curl \
 -X POST  \
 -H "Content-Type: application/json" \
 -H "Authorization: EXAMPLE-API-TOKEN" \
 --data '{ "messages": [{ "role": "user", "content": "What cities had the highest aov last year?" }], "runQuery": true}' \
 https://YOUR_CUBE_API/cubejs-api/v1/ai/query/completions
```

Example response:

```json
{
    "message": "To find the city with the highest average order value for last year, we'll analyze the data by city and calculate the average order value for each. The query will group the results by users' city and sort them to identify the city with the highest average order value.",
    "cube_query": {
        "measures": [
            "orders_view.average_order_value"
        ],
        "dimensions": [
            "orders_view.users_city"
        ],
        "timeDimensions": [
            {
                "dimension": "orders_view.created_at",
                "dateRange": "last year",
                "granularity": "year"
            }
        ],
        "order": {
            "orders_view.average_order_value": "desc"
        },
        "limit": 1
    }
}
{
    "query": {
        "measures": [
            "orders_view.average_order_value"
        ],
        "dimensions": [
            "orders_view.users_city"
        ],
        "timeDimensions": [
            {
                "dimension": "orders_view.created_at",
                "dateRange": [
                    "2023-01-01T00:00:00.000",
                    "2023-12-31T23:59:59.999"
                ],
                "granularity": "year"
            }
        ],
        "order": [
            {
                "id": "orders_view.average_order_value",
                "desc": true
            }
        ],
        "limit": 1,
        "timezone": "UTC",
        "filters": [],
        "rowLimit": 1
    },
    "data": [
        {
            "orders_view.users_city": "San Francisco",
            "orders_view.created_at.year": "2023-01-01T00:00:00.000",
            "orders_view.created_at": "2023-01-01T00:00:00.000",
            "orders_view.average_order_value": "322.619048"
        }
    ],
    "lastRefreshTime": "2024-05-08T18:24:14.623Z",
    "annotation": {
        "measures": {
            "orders_view.average_order_value": {
                "title": "Orders View Average Order Value",
                "shortTitle": "Average Order Value",
                "type": "number",
                "drillMembers": [],
                "drillMembersGrouped": {
                    "measures": [],
                    "dimensions": []
                }
            }
        },
        "dimensions": {
            "orders_view.users_city": {
                "title": "Orders View Users City",
                "shortTitle": "Users City",
                "type": "string"
            }
        },
        "segments": {},
        "timeDimensions": {
            "orders_view.created_at.year": {
                "title": "Orders View Created at",
                "shortTitle": "Created at",
                "type": "time"
            },
            "orders_view.created_at": {
                "title": "Orders View Created at",
                "shortTitle": "Created at",
                "type": "time"
            }
        }
    },
    "dataSource": "default",
    "dbType": "snowflake",
    "extDbType": "cubestore",
    "external": false,
    "slowQuery": false,
    "total": null
}
```
